Crate ureq[−][src]

ureq is a minimal request library.

The goals of this library are:

Minimal dependency tree
Obvious API
Blocking API
Convenience over correctness
No use of unsafe

// requires feature: `ureq = { version = "*", features = ["json"] }`
use ureq::json;

fn main() -> std::io::Result<()> {
  // sync post request of some json.
  let resp = ureq::post("https://myapi.example.com/ingest")
      .set("X-My-Header", "Secret")
      .send_json(json!({
          "name": "martin",
          "rust": true
      }));

  // .ok() tells if response is 200-299.
  if resp.ok() {
    println!("success: {}", resp.into_string()?);
  } else {
    // This can include errors like failure to parse URL or connect timeout.
    // They are treated as synthetic HTTP-level error statuses.
    println!("error {}: {}", resp.status(), resp.into_string()?);
  }
  Ok(())
}

Plain requests

Most standard methods (GET, POST, PUT etc), are supported as functions from the top of the library (ureq::get, ureq::post, ureq::put, etc).

These top level http method functions create a Request instance which follows a build pattern. The builders are finished using:

.call() without a request body.
.send() with a request body as Read (chunked encoding support for non-known sized readers).
.send_string() body as string.
.send_bytes() body as bytes.
.send_form() key-value pairs as application/x-www-form-urlencoded.

JSON

By enabling the ureq = { version = "*", features = ["json"] } feature, the library supports serde json.

request.send_json() send body as serde json.
response.into_json() transform response to json.

Agents

To maintain a state, cookies, between requests, you use an agent. Agents also follow the build pattern. Agents are created with ureq::agent().

Content-Length

The library will set the content length on the request when using .send_string() or .send_json(). In other cases the user can optionally request.set("Content-Length", 1234).

For responses, if the Content-Length header is present, the methods that reads the body (as string, json or read trait) are all limited to the length specified in the header.

Transfer-Encoding: chunked

Dechunking is a response body is done automatically if the response headers contains a Transfer-Encoding header.

Sending a chunked request body is done by setting the header prior to sending a body.

let resp = ureq::post("http://my-server.com/ingest")
    .set("Transfer-Encoding", "chunked")
    .send_string("Hello world");

Character encoding

By enabling the ureq = { version = "*", features = ["charset"] } feature, the library supports sending/receiving other character sets than utf-8.

For response.into_string() we read the header Content-Type: text/plain; charset=iso-8859-1 and if it contains a charset specification, we try to decode the body using that encoding. In the absence of, or failing to interpret the charset, we fall back on utf-8.

Similarly when using request.send_string(), we first check if the user has set a ; charset=<whatwg charset> and attempt to encode the request body using that.

Synthetic errors

Rather than exposing a custom error type through results, this library has opted for representing potential connection/TLS/etc errors as HTTP response codes. These invented codes are called “synthetic.”

The idea is that from a library user’s point of view the distinction of whether a failure originated in the remote server (500, 502) etc, or some transient network failure, the code path of handling that would most often be the same.

As a result, reading from a Response may yield an error message generated by the ureq library. To handle these errors, use the response.synthetic_error() method.

Macros

json	Construct a `serde_json::Value` from a JSON literal.

Structs

Agent	Agents keep state between requests.
Cookie	Representation of an HTTP cookie.
Header	Wrapper type for a header field. https://tools.ietf.org/html/rfc7230#section-3.2
Proxy	Proxy server definition
Request	Request instances are builders that creates a request.
Response	Response instances are created as results of firing off requests.
SerdeMap	Represents a JSON key/value type.

Enums

Error	Errors that are translated to “synthetic” responses.
SerdeValue	Represents any valid JSON value.

Traits

Resolver

Functions

agent	Agents are used to keep state between requests.
delete	Make a DELETE request.
get	Make a GET request.
head	Make a HEAD request.
options	Make an OPTIONS request.
patch	Make an PATCH request.
post	Make a POST request.
put	Make a PUT request.
request	Make a request setting the HTTP method via a string.
serde_to_value	Convert a `T` into `serde_json::Value` which is an enum that can represent any valid JSON data.
trace	Make a TRACE request.

Crate ureq⎘[−][src]

Crate ureq[−][src]